package com.android.internal.telephony;

import android.os.Bundle;
import java.util.List;
import android.telephony.NeighboringCellInfo;

/*
 * Copyright (C) 2007 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
interface ITelephony {

	/**
	 * Dial a number. This doesn't place the call. It displays the Dialer
	 * screen.
	 * 
	 * @param number
	 *            the number to be dialed. If null, this would display the
	 *            Dialer screen with no number pre-filled.
	 */
	void dial(String number);

	/**
	 * Place a call to the specified number.
	 * 
	 * @param number
	 *            the number to be called.
	 */
	void call(String number);

	/**
	 * If there is currently a call in progress, show the call screen. The DTMF
	 * dialpad may or may not be visible initially, depending on whether it was
	 * up when the user last exited the InCallScreen.
	 *
	 * @return true if the call screen was shown.
	 */
	boolean showCallScreen();

	/**
	 * Variation of showCallScreen() that also specifies whether the DTMF
	 * dialpad should be initially visible when the InCallScreen comes up.
	 *
	 * @param showDialpad
	 *            if true, make the dialpad visible initially, otherwise hide
	 *            the dialpad initially.
	 * @return true if the call screen was shown.
	 *
	 * @see showCallScreen
	 */
	boolean showCallScreenWithDialpad(boolean showDialpad);

	/**
	 * End call or go to the Home screen
	 *
	 * @return whether it hung up
	 */
	boolean endCall();

	/**
	 * Answer the currently-ringing call.
	 *
	 * If there's already a current active call, that call will be automatically
	 * put on hold. If both lines are currently in use, the current active call
	 * will be ended.
	 *
	 * TODO: provide a flag to let the caller specify what policy to use if both
	 * lines are in use. (The current behavior is hardwired to
	 * "answer incoming, end ongoing", which is how the CALL button is specced
	 * to behave.)
	 *
	 * TODO: this should be a oneway call (especially since it's called directly
	 * from the key queue thread).
	 */
	void answerRingingCall();

	/**
	 * Silence the ringer if an incoming call is currently ringing. (If
	 * vibrating, stop the vibrator also.)
	 *
	 * It's safe to call this if the ringer has already been silenced, or even
	 * if there's no incoming call. (If so, this method will do nothing.)
	 *
	 * TODO: this should be a oneway call too (see above). (Actually *all* the
	 * methods here that return void can probably be oneway.)
	 */
	void silenceRinger();

	/**
	 * Check if we are in either an active or holding call
	 * 
	 * @return true if the phone state is OFFHOOK.
	 */
	boolean isOffhook();

	/**
	 * Check if an incoming phone call is ringing or call waiting.
	 * 
	 * @return true if the phone state is RINGING.
	 */
	boolean isRinging();

	/**
	 * Check if the phone is idle.
	 * 
	 * @return true if the phone state is IDLE.
	 */
	boolean isIdle();

	/**
	 * Check to see if the radio is on or not.
	 * 
	 * @return returns true if the radio is on.
	 */
	boolean isRadioOn();

	/**
	 * Check if the SIM pin lock is enabled.
	 * 
	 * @return true if the SIM pin lock is enabled.
	 */
	boolean isSimPinEnabled();

	/**
	 * Cancels the missed calls notification.
	 */
	void cancelMissedCallsNotification();

	/**
	 * Supply a pin to unlock the SIM. Blocks until a result is determined.
	 * 
	 * @param pin
	 *            The pin to check.
	 * @return whether the operation was a success.
	 */
	boolean supplyPin(String pin);

	/**
	 * Handles PIN MMI commands (PIN/PIN2/PUK/PUK2), which are initiated without
	 * SEND (so <code>dial</code> is not appropriate).
	 * 
	 * @param dialString
	 *            the MMI command to be executed.
	 * @return true if MMI command is executed.
	 */
	boolean handlePinMmi(String dialString);

	/**
	 * Toggles the radio on or off.
	 */
	void toggleRadioOnOff();

	/**
	 * Set the radio to on or off
	 */
	boolean setRadio(boolean turnOn);

	/**
	 * Request to update location information in service state
	 */
	void updateServiceLocation();

	/**
	 * Enable location update notifications.
	 */
	void enableLocationUpdates();

	/**
	 * Disable location update notifications.
	 */
	void disableLocationUpdates();

	/**
	 * Enable a specific APN type.
	 */
	int enableApnType(String type);

	/**
	 * Disable a specific APN type.
	 */
	int disableApnType(String type);

	/**
	 * Allow mobile data connections.
	 */
	boolean enableDataConnectivity();

	/**
	 * Disallow mobile data connections.
	 */
	boolean disableDataConnectivity();

	/**
	 * Report whether data connectivity is possible.
	 */
	boolean isDataConnectivityPossible();

	Bundle getCellLocation();

	/**
	 * Returns the neighboring cell information of the device.
	 */
	List<NeighboringCellInfo> getNeighboringCellInfo();

	int getCallState();

	int getDataActivity();

	int getDataState();

}
